Data Structures5

This section shows the Pascal data structure for the GDevice record, which can contain information about a video device or an offscreen graphics world. This section also shows the data structure for the DeviceLoopFlags data type, which defines a set of options you can specify to the DeviceLoop procedure.

GDevice

Color QuickDraw stores state information for video devices and offscreen graphics worlds in GDevice records. When the system starts up, it allocates and initializes one handle to a GDevice record for each video device it finds. When you use the NewGWorld function (described in the chapter "Offscreen Graphics Worlds" in this book), Color QuickDraw automatically creates a GDevice record for the new offscreen graphics world. The system links these GDevice records in a list, called the device list . (You can find a handle to the first element in the device list in the global variable DeviceList .) By default, the GDevice record corresponding to the first video device found is marked as the current device; all other graphics devices in the list are initially marked as inactive.

Printing graphics ports, described in the chapter "Printing Manager" in this book, do not have GDevice records.

When the user moves a window or creates a window on another screen, and your application draws into that window, Color QuickDraw automatically makes the video device for that screen the current device. Color QuickDraw stores that information in the global variable TheGDevice .

GDevice records that correspond to video devices have drivers associated with them. These drivers can be used to change the mode of the video device from black and white to color and to change the pixel depth. The set of routines supported by a video driver is defined and described in Designing Cards and Drivers for the Macintosh Family , third edition. Application-created GDevice records usually don't require drivers.

A GDevice record is defined as follows:



 
TYPE GDevice = 

RECORD

    gdRefNum:           Integer;            {reference number of screen }

                                            { driver}

    gdID:               Integer;            {reserved; set to 0}

    gdType:             Integer;            {device type--indexed or direct}

    gdITable:           ITabHandle;         {handle to inverse table for }

                                            { Color Manager}

    gdResPref:          Integer;            {preferred resolution}

    gdSearchProc:       SProcHndl;          {handle to list of search }

                                            { functions}

    gdCompProc:         CProcHndl;          {handle to list of complement }

                                            { functions}

    gdFlags:            Integer;            {graphics device flags}

    gdPMap:             PixMapHandle;       {handle to PixMap record for }

                                            { displayed image}

    gdRefCon:           LongInt;            {reference value}

    gdNextGD:           GDHandle;           {handle to next graphics device}

    gdRect:             Rect;               {graphics device's global bounds}

    gdMode:             LongInt;            {graphics device's current mode}

    gdCCBytes:          Integer;            {width of expanded cursor data}

    gdCCDepth:          Integer;            {depth of expanded cursor data}

    gdCCXData:          Handle;             {handle to cursor's expanded }

                                            { data}

    gdCCXMask:          Handle;             {handle to cursor's expanded }

                                            { mask}

    gdReserved:         LongInt;            {reserved for future use--must }

                                            { be 0}

END;

gdRefNum: The reference number of the driver for the screen associated with the video device. For most video devices, this information is set at system startup time.
gdID: Reserved. If you create your own GDevice record, set this field to 0.
gdType: The general type of graphics device. Values include



 
                    CONST

                    clutType = 0;           {CLUT device--that is, one with }

                                            { colors mapped with a color }

                                            { lookup table}

                    fixedType = 1;          {fixed colors--that is, the }

                                            { color lookup table can't }

                                            { be changed}

                    directType = 2;         {direct RGB colors}

These types are described in more detail in the chapter "Color Manager" in Inside Macintosh: Advanced Color Imaging .
gdITable: A handle to the inverse table for color mapping; the inverse table is described in the chapter "Color Manager" in Inside Macintosh: Advanced Color Imaging .
gdResPref: The preferred resolution for inverse tables.
gdSearchProc: A handle to the list of search functions, as described in the chapter "Color Manager" in Inside Macintosh: Advanced Color Imaging ; its value is NIL for the default function.
gdCompProc: A handle to a list of complement functions, as described in the chapter "Color Manager" in Inside Macintosh: Advanced Color Imaging ; its value is NIL for the default function.
gdFlags: The GDevice record's attributes. To set the attribute bits in the gdFlags field, use the SetDeviceAttribute procedure (described on SetDeviceAttribute )--do not set these flags directly in the GDevice record. The constants representing each bit are listed here.



 
CONST {flag bits for gdFlags field of GDevice record}

gdDevType           = 0;    {if bit is set to 0, graphics device is }

                            { black and white; if set to 1, }

                            { graphics device supports color}

burstDevice         = 7;    {if bit is set to 1, graphics device }

                            { supports block transfer}

ext32Device         = 8;    {if bit is set to 1, graphics device }

                            { must be used in 32-bit mode}

ramInit             = 10;   {if bit is set to 1, graphics device has }

                            { been initialized from RAM}

mainScreen          = 11;   {if bit is set to 1, graphics device is }

                            { the main screen}

allInit             = 12;   {if bit is set to 1, all graphics devices }

                            { were initialized from 'scrn' resource}

screenDevice        = 13;   {if bit is set to 1, graphics device is }

                            { a screen}

noDriver            = 14;   {if bit is set to 1, GDevice }

                            { record has no driver}

screenActive        = 15;   {if bit is set to 1, graphics device is }

                            { active}

gdPMap: A handle to a PixMap record giving the dimension of the image buffer, along with the characteristics of the graphics device (resolution, storage format, color depth, and color table). PixMap records are described in the chapter "Color QuickDraw" in this book. For GDevice records, the high bit of the global variableTheGDevice^^.gdPMap^^.pmTable^^.ctFlags is always set.
gdRefCon: A value used by system software to pass device-related parameters. Since a graphics device is shared, you shouldn't store data here.
gdNextGD: A handle to the next graphics device in the device list. If this is the last graphics device in the device list, the field contains 0.
gdRect: The boundary rectangle of the graphics device represented by the GDevice record. The main screen has the upper-left corner of the rectangle set to (0,0). All other graphics devices are relative to this point.
gdMode: The current setting for the graphics device mode. This value is passed to the video driver to set its pixel depth and to specify color or black and white; applications don't need this information. See Designing Cards and Drivers for the Macintosh Family , third edition, for more information about the modes specified in this field.
gdCCBytes: The rowBytes value of the expanded cursor. Your application should not change this field. Cursors are described in the chapter "Cursor Utilities."
gdCCDepth: The depth of the expanded cursor. Your application should not change this field.
gdCCXData: A handle to the cursor's expanded data. Your application should not change this field.
gdCCXMask: A handle to the cursor's expanded mask. Your application should not change this field.
gdReserved: Reserved for future expansion; it must be set to 0 for future compatibility.

Your application should never need to directly change the fields of a GDevice record. If you find it absolutely necessary for your application to so, immediately use the GDeviceChanged procedure to notify Color QuickDraw that your application has changed the GDevice record. The GDeviceChanged procedure is described in the chapter "Color QuickDraw" in this book.

DeviceLoopFlags

When you use the DeviceLoop procedure (described on DeviceLoop ), you can change its default behavior by using the flags parameter to specify one or more members of the set of flags defined by the DeviceLoopFlags data type. These flags are described here; if you want to use the default behavior of DeviceLoop , pass in the flags parameter 0 in your C code or an empty set ([ ]) in your Pascal code.



 
TYPE DeviceLoopFlags = 

SET OF                      {for flags parameter of DeviceLoop}

    (singleDevices,         {DeviceLoop doesn't group similar graphics }

                            { devices when calling drawing procedure}

    dontMatchSeeds,         {DeviceLoop doesn't consider ctSeed fields }

                            { of ColorTable records for graphics }

                            { devices when comparing them}

    allDevices);            {DeviceLoop ignores value of drawingRgn }

                            { parameter--instead, it calls drawing }

                            { procedure for every screen}

singleDevices: If this flag is not set, DeviceLoop calls your drawing procedure only once for each set of similar graphics devices, and the first one found is passed as the target device. (It is assumed to be representative of all the similar graphics devices.) If you set the singleDevices flag, then DeviceLoop does not group similar graphics devices--that is, those having identical pixel depths, black-and-white or color settings, and matching color table seeds--when it calls your drawing procedure.
dontMatchSeeds: If you set the dontMatchSeeds flag, then DeviceLoop doesn't consider color table seeds when comparing graphics devices for similarity; DeviceLoop ignores this flag if you set the singleDevices flag. Used primarily by the Palette Manager, the ctSeed field of a ColorTable record is described in the chapter "Color QuickDraw" in this book.
allDevices: If you set the allDevices flag, DeviceLoop ignores the drawingRgn parameter and calls your drawing procedure for every graphics device. The value of current graphics port's visRgn field is not affected when you set this flag.